home *** CD-ROM | disk | FTP | other *** search
-
-
-
-
- APLOCK 1.0
- Tom Thompson
-
- (C) Copyright 1988 by CBIS, Inc.
- 5875 Peachtree Industrial Blvd
- Atlanta GA 30092
- (404) 446-1332
-
- APLOCK is used to synchronize network access to single user
- applications. Instead of running the application directly, a
- BATCH file containing the name of the application and appropriate
- APLOCK commands is executed. The ERRORLEVEL codes returned by
- APLOCK are used to control the flow of the BATCH program.
- If you are familiar with constructing BATCH files to execute
- other programs, then APLOCK'ed applications are easy to set up.
-
- Let's start with an example. Assume that you have a program,
- named ORDER.EXE, that everyone on the network needs to use. It
- can only be run by one person at a time. Each person needs to
- use it several times a day, but fairly infrequently and only for
- a few minutes each time. The multi-user version of ORDER is
- either expensive or not-available, and it is too awkward to
- always check to see if anyone is currently in the program as a
- means of synchronization.
-
- This is a perfect application for APLOCK. Set the system up as
- follows:
-
- - Everyone has access to the application in D:\APPS.
- - Everyone has access to a subdirectory E:\LOCKS (which
- will hold APLOCK control files).
- - ORDER.EXE is renamed to ORDERPRG.EXE.
- - Everyone has a path to the BATCH file ORDER.BAT
- (described below) and to APLOCK.EXE.
- - ORDER.BAT and APLOCK.EXE are set read-only with the
- ATTRIB command (ATTRIB +R filename).
-
- The contents of ORDER.BAT are shown below. The line numbers are
- for reference, and do not actually appear in the file.
-
- 1 ECHO OFF
- 2 APLOCK LOCK E:\LOCKS\ORDER.LOK Program in use by $n since $t.
- 3 IF ERRORLEVEL 1 GOTO DONE
- 4 D:
- 5 CD\APPS
- 6 ORDERPRG
- 7 APLOCK UNLOCK E:\LOCKS\ORDER.LOK
- 8 :DONE
-
-
-
- Now, when ORDER is entered from the keyboard, the BATCH file
- (instead of the program) is executed. The first time APLOCK is
- called (line 2), it looks to see if the file ORDER.LOK exists in the
- E:\LOCKS directory. There are three possibilities:
-
- (1) ORDER.LOK does not exist. In this case, APLOCK creates
- ORDER.LOK and stores in it the user's machine name and
- time of day. APLOCK then returns with ERRORLEVEL 0.
-
-
- (2) ORDER.LOK exists, and its contents indicate it was
- created earlier from this same machine. In this case,
- APLOCK simply returns with ERRORLEVEL 0.
-
- (3) ORDER.LOK exists and was created by another machine.
- In this case, APLOCK displays the message "Program in
- use by nnnn since hh:mm", where nnnn and hh:mm were
- stored in ORDER.LOK by another user. APLOCK then
- returns with ERRORLEVEL 1.
-
- Now, when line 3 of the BATCH file is executed, it uses the
- ERRORLEVEL from line 2 to determine whether to continue normally
- to line 4, or skip down to line 8. In other words, if some other
- user had (via the BATCH file) already created an ORDER.LOK file,
- then actual execution of the application is bypassed.
-
- Assume that APLOCK returned ERRORLEVEL 0 and the application is
- run (lines 4, 5, and 6). When the user exits the application,
- control is returned to line 7 of the BATCH file, which invokes
- APLOCK again. However this time the "key word" is UNLOCK instead
- of LOCK. This causes APLOCK to go delete the file ORDER.LOK,
- thereby "freeing" the application for use by another.
-
-
- Four APLOCK commands are possible. The syntax is shown below:
-
- APLOCK LOCK <lockfile> <message>
-
- APLOCK UNLOCK <lockfile>
-
- APLOCK KILL <lockfile>
-
- APLOCK CLEANUP <lockfile> [<lockfile2> ... ]
-
- For the discussion below, these four formats will be referred to
- as the LOCK, UNLOCK, KILL and CLEANUP commands respectively.
- <lockfile> is the path/name of a control file used by APLOCK. It
- is unique for a given application. <message> is displayed by the
- LOCK command whenever the use of the application cannot be
- acquired. It can include the special strings $n, $d, and $t.
- These will be replaced by the name, lock date, and lock time of
- the user that has locked the application.
-
-
-
- LOCK Command
-
- This command returns ERRORLEVEL 0 if <lockfile> does not exist or
- if it exists and the contents of <lockfile> indicate it was
- created by the same machine (that's executing the LOCK command).
- If <lockfile> does exist and was created by another user, then
- ERRORLEVEL 1 is returned and <message> is displayed. If a
- "system error" exists, then ERRORLEVEL 2 is returned. See below
- for more information on system errors.
-
-
- UNLOCK Command
-
- This command checks for the presence of <lockfile>. If it exists
- and it's contents indicate it was created by the same user, it is
- deleted. ERRORlevel 0 is returned. If a "system error" exists,
- then ERRORLEVEL 1 is returned. See below for more information on
- system errors.
-
-
- KILL Command
-
- KILL is used to delete <lockfile> regardless of which user is
- created. This returns ERRORLEVEL 0 (or 1 if a system error
- exists). Referring to the example presented earlier, assume that
- a user executing ORDER.BAT turned off the machine and went home
- just as line 5 was being executed (and locked her office!). This
- would leave <lockfile> created and not "deletable" with the
- UNLOCK command. You could make a batch file called OVERRIDE that
- contained the following:
-
- 1 ECHO OFF
- 2 APLOCK LOCK E:\LOCKS\ORDER.LOK Locked by $n since $t.
- 3 IF NOT ERRORLEVEL 1 GOTO NOTLOCKED
- 4 ECHO About to override! Control-C, then Y to cancel!
- 5 PAUSE
- 6 APLOCK KILL E:\LOCKS\ORDER.LOK
- 7 :NOTLOCKED
-
-
-
- CLEANUP Command
-
- CLEANUP takes multiple <lockfile> arguments. For each <lockfile>
- it looks to see if it exists and was created by the same user.
- If so, that file is deleted. CLEANUP returns ERRORLEVEL 0 (or 1
- for a system error). This should be put in AUTOEXEC.BAT (or
- similar startup point). For example, if the user reset the
- machine just as line 5 in the main example was being executed,
- and
-
- APLOCK CLEANUP E:\LOCKS
-
- was in the start-up batch files (after network setup), then the
- locked condition would be "cleaned up" before anybody noticed.
-
-
-
- SYSTEM ERRORS
-
- As in any multi-user program, there is always a small period of
- time when a program is executing that files are open, records are
- locked, etc. and loss of power or control at the user machine
- will leave files inaccessible by other users. If this happens to
- APLOCK, an appropriate error message is printed and the file is
- identified. Sometimes the network can correct this condition in
- a few minutes (or sooner if the offending workstation is
- restarted). Some cases may require taking the server down and
- bringing it back up. Other "system errors" are more mundane --
- things like invalid directory paths. Shown below is the general
- format of the error display, followed by a list of possible
- errors.
-
- APLOCK ERROR: <error message>
- Command = <key word>, Filename = <lock file>
-
-
- - Bad syntax
- - Invalid path for create lock file
- - Write error when creating lock file
- - Timed out attempting to access lock file
- (Another user stuck?)
- - Could not delete lock file
- - Timed out attempting to delete lock file
- (Another user stuck?)
- - Invalid path for lock file
- - Cannot read lock file
- - Bad data format in lock file
-
-
- The time out errors take abount 10 seconds to occur, since it is
- normal for the <lockfile> to be inaccessible for short periods of
- time.
-
-
-
- REMINDERS and HINTS
-
- Set APLOCK.EXE and batch files that call it read-only, so you
- won't get sharing violations (or set them sharable with SATTRIB
- or FLAG).
-
- You can lock more than just programs. Everybody could use the
- same program, but "lock" a subdirectory full of data files to be
- processed by the program.
-
- Make sure that "E:\LOCKS" (for instance) really addresses the
- same physical directory for every user.
-
- For added protection against the user running the program
- directly, let the BATCH file NWUSE a drive containing the
- application, then NWUSE /D it when done.
-
-